Day 2 | 武器庫點交：環境建置與 Agents CLI 快速起手式

主張：adk create 跟 Agents CLI 不是同一件事的兩種寫法，是為完全不同目的設計的兩條路——選錯起手式，後面遲早要重來一次。
讀完能做到：判斷自己現在該用哪一條路徑起手，並實際跑起你的第一個 ADK agent。

兩條路，先選對再上路

昨天我們認識了 ADK 的設計哲學，今天要正式動手。但在打第一行指令之前，有一個決定會影響你接下來一整個系列的體驗:ADK 官方文件明確區分了兩條入門路徑，而它們不是同一件事的兩種寫法，是為完全不同目的設計的。

第一條路是 adk create——一個指令產生一個最精簡的單檔 agent 專案，幾分鐘內就能跑起來，適合純粹學習 ADK 語法與概念。第二條路是 Agents CLI——一整套工具鏈，產生的專案自帶測試、評估資料集、CI/CD 用的 Dockerfile，適合你真的打算把這個 agent 測試、評估、部署上線。

這個系列會兩條路都示範，但今天先從最基礎、最快能看到成果的路徑走起。

路徑 A：adk create——五分鐘跑起第一個 agent

先處理環境。ADK 的 Python 套件要求 Python 3.10 以上版本，官方建議用虛擬環境隔離依賴:

python3 -m venv .venv

依作業系統啟用虛擬環境:

# Mac / Linux
source .venv/bin/activate

# Windows CMD:
.venv\Scripts\activate.bat

# Windows PowerShell:
.venv\Scripts\Activate.ps1

安裝 ADK:

pip install google-adk

接著建立一個新的 agent 專案:

adk create my_agent

這個指令會產生以下結構:

my_agent/
    agent.py      # main agent code
    .env          # API keys or project IDs
    __init__.py

這一行不是打完就靜靜跑完的指令，它會先跳出一小段互動精靈，第一次遇到很容易愣住。照順序會問你兩件事。

第一件事是選模型:

Choose a model for the root agent:
1. gemini-3.5-flash
2. Other models (fill later)
Choose model (1, 2):

選 1 會直接把 gemini-3.5-flash 寫進 agent.py；選 2 則是先跳過，留給你自己動手改。這裡有一個容易對不起來的地方:接下來要展示的官方快速入門範例程式碼用的是 model='gemini-flash-latest'，跟精靈預設寫進去的 gemini-3.5-flash 不是同一個字串。兩個都是合法的模型代號，差別留到 Day 3 講模型與版本標記時再展開，這裡先知道「精靈幫你選的」跟「文件範例裡寫的」可能長得不一樣，不用懷疑是自己裝錯版本。

第二件事是選後端，也是最容易卡關的一步:

1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3):

選 1(Google AI)對應下一節要走的 Gemini API 金鑰路線，選 2(Vertex AI)對應你已經有 Google Cloud 專案的情況。第三個選項「Login with Google」，它的作用是幫你走 Application Default Credentials(ADC)瀏覽器登入。

官方文件強調一件事:agent.py 裡的 root_agent 定義，是一個 ADK agent唯一必要的元素。其他一切(工具、子 agent、callback)都是可選的擴充。快速入門的範例會請你更新 agent.py，加入一個時間查詢工具:

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
    model='gemini-3.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

這段程式碼雖然簡單，但已經展示了明天(Day 3)要深入的三個要素:model 決定用哪個模型、instruction 決定行為指引、tools 給它行動能力。

設定 API 金鑰

這個範例走的是 Gemini API，需要一把 API 金鑰。到 Google AI Studio 的 API Keys 頁面建立一把，然後寫進 .env:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env

跑起來

ADK 提供兩種互動方式來測試你的 agent:

命令列介面:

adk run my_agent

Web 介面:

adk web --port 8000

這裡有一個新手最容易卡住的地方，官方文件用一個獨立的 Note 特別強調:這個指令要在包含 my_agent/ 資料夾的父目錄執行。舉例來說，如果你的 agent 放在 agents/my_agent/ 底下，你要在 agents/ 這一層跑 adk web，而不是進到 my_agent/ 裡面跑。跑起來之後，瀏覽器打開 http://localhost:8000，左上角選擇你的 agent，就能開始對話。

還有一件事幾乎出現在每一頁快速入門裡，重要到值得重複第二次:ADK Web 只是用來開發與除錯的工具，不是給生產環境用的。

路徑 B：Agents CLI——為上線準備的完整鷹架

先安裝 uv 環境 (uv 是使用 Rust 開發的極速 Python 套件與專案管理工具，整合了套件安裝、虛擬環境管理、Python 版本管理等功能):

MacOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

如果你已經知道這個 agent 最終要測試、評估、部署，直接跳過 adk create，改用 Agents CLI。安裝方式:

uvx google-agents-cli setup

這個指令一次做完三件事:安裝 agents-cli 指令本身、安裝 ADK Python 套件，以及把 ADK 開發技能(skills)裝進你機器上已經有的 coding agent(例如 Claude Code、Cursor、Antigravity)。注意它不會順便幫你生一個專案——setup 只負責把工具裝好，真正建立專案要另外呼叫 create:

agents-cli create my-first-agent --prototype --yes
cd my-first-agent
agents-cli install

--prototype 先跳過 Terraform 與 CI/CD，只留 agent 本體，適合現在這種「先確認能跑」的階段；--yes 代表所有互動問題都採預設值，不用一路按 Enter。agents-cli install 則是透過 uv sync 把這個專案需要的 Python 套件裝起來，一定要在剛剛建立的專案資料夾裡執行。

跑完 create 之後，你會得到跟 adk create 的極簡版天差地遠的專案結構:

my-agent/
    app/
        agent.py                # main agent code
        fast_api_app.py         # server, telemetry, and routes
        app_utils/              # session and artifact services
    tests/
        eval/                   # evaluation datasets and metrics
        integration/            # end-to-end agent tests
        unit/
    pyproject.toml              # project config and dependencies
    agents-cli-manifest.yaml    # Agents CLI configuration
    Dockerfile                  # container image for deployment
    GEMINI.md                   # project guidance for coding agents
    .env                        # API keys or project IDs

注意這裡多出來的東西:fast_api_app.py(伺服器、遙測、路由)、tests/eval/(評估資料集)、Dockerfile(部署用的容器映像)。這些正是 Day 26 之後「實彈演習」篇會用到的骨架——如果你現在就知道自己要走完整條路，現在用 Agents CLI 建專案，能省下之後重新架設的功夫。

專案建好、依賴裝完之後，要本機試跑，用:

agents-cli playground

這會啟動一個支援熱重載的 ADK web 介面，預設在 http://localhost:8080。如果只想從終端機丟一句話測試、不開瀏覽器，還有:

agents-cli run "請介紹什麼是 RAG"

agents-cli run 會送出單一 prompt,直接把 agent 的回應印在 terminal 裡。

開始之前的檢查清單

在動手之前，先確認以下工具都已就緒——這份清單同時涵蓋兩條路徑，如果你只走路徑 A，前三項就夠了:

• Python 3.11 以上(注意:這是 Agents CLI 的要求，比 ADK 函式庫本身的 3.10 更高一個版本——這個差異很容易被忽略，如果你的環境卡在 3.10.x，裝 Agents CLI 時會出問題)
• uv 工具，管理環境與依賴
• Node.js，用來安裝 Agents CLI 的 skills
• 一個支援 skills 的 coding agent，例如 Antigravity、Claude Code、或 Codex

如果你之後要部署，還需要額外裝好 Google Cloud CLI 與 Terraform——這兩樣現在可以先不裝，系列第五篇再回來處理。

今天的收穫，以及留給明天的伏筆

到這裡，你應該已經有一個能跑的 ADK 環境，不管是走 adk create 的極簡版，還是走 Agents CLI 的完整鷹架。兩條路徑產生的 root_agent 定義，骨架其實是同一套 API——這就是明天要深入的主題:一個 agent 到底由哪些必要成分組成、instruction 該怎麼寫、tools 除了直接塞函式之外還有哪些形態。